{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Variational Inference using ADVI\n", "\n", "Variational inference is a method for approximating complex Bayesian posterior distributions using simpler, parameterized distributions.\n", "The Automatic Differentiation Variational Inference (ADVI) algorithm\n", "searches over a family of simple densities to find the best\n", "approximate posterior density.\n", "ADVI produces an estimate of the parameter means together with a sample\n", "from the approximate posterior density.\n", "\n", "ADVI uses stochastic gradient ascent to approximate the variational objective function, the evidence lower bound or ELBO.\n", "The algorithm ascends these gradients using an adaptive stepsize sequence\n", "that has one parameter ``eta`` which is adjusted during warmup.\n", "The number of draws used to approximate the ELBO is denoted by ``elbo_samples``. \n", "ADVI heuristically determines a rolling window over which it computes\n", "the average and the median change of the ELBO.\n", "When this change falls below a threshold, denoted by ``tol_rel_obj``,\n", "the algorithm is considered to have converged." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Example: variational inference for model ``bernoulli.stan``\n", "\n", "The [CmdStanModel variational](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanModel.variational) method\n", "wraps the CmdStan [variational](https://mc-stan.org/docs/cmdstan-guide/variational_config.html) method." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import os\n", "from cmdstanpy.model import CmdStanModel\n", "from cmdstanpy.utils import cmdstan_path\n", "\n", "bernoulli_dir = os.path.join(cmdstan_path(), 'examples', 'bernoulli')\n", "stan_file = os.path.join(bernoulli_dir, 'bernoulli.stan')\n", "data_file = os.path.join(bernoulli_dir, 'bernoulli.data.json')\n", "# instantiate, compile bernoulli model\n", "model = CmdStanModel(stan_file=stan_file)\n", "# run CmdStan's variational inference method, returns object `CmdStanVB`\n", "vi = model.variational(data=data_file)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The [CmdStanVB](https://mc-stan.org/cmdstanpy/api.html#cmdstanvb) object provides the following properties to access information about the parameter names, estimated means, and the sample:\n", "\n", " + `column_names` - list of column names\n", " + `columns` - number of columns\n", " + `eta` - step size scaling parameter\n", " + `variational_params_dict` - inferred parameter means as a Dict.\n", " + `variational_params_np` - inferred parameter means as a numpy.ndarray.\n", " + `variational_params_pd` - inferred parameter means as a pandas.DataFrame.\n", " + `variational_sample` - the set of approximate posterior output draws ad a numpy.ndarray.\n", " + `variational_sample_pd` - the set of approximate posterior output draws ad a pandas.DataFrame." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "scrolled": true }, "outputs": [], "source": [ "print(vi.column_names)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(vi.variational_params_dict['theta'])" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "print(vi.variational_sample.shape)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "These estimates are only valid if the algorithm has converged to a good\n", "approximation. When the algorithm fails to do so, the `variational`\n", "method will throw a `RuntimeError`.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "tags": [ "raises-exception" ] }, "outputs": [], "source": [ "model_fail = CmdStanModel(stan_file='eta_should_fail.stan')\n", "vi_fail = model_fail.variational()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Unless you set `require_converged=False`:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "vi_fail = model_fail.variational(require_converged=False)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This lets you inspect the output to try to diagnose the issue with the model" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "vi_fail.variational_params_dict" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "See the [API documentation](https://mc-stan.org/cmdstanpy/api.html#cmdstanpy.CmdStanModel.variational) for a full description of all arguments." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.16" } }, "nbformat": 4, "nbformat_minor": 4 }